1 /**
2 * Copyright (C) 2006-2019 INRIA and contributors
3 *
4 * Spoon is available either under the terms of the MIT License (see LICENSE-MIT.txt) of the Cecill-C License (see LICENSE-CECILL-C.txt). You as the user are entitled to choose the terms under which to adopt Spoon.
5 */
6 package spoon;
7
8 import spoon.compiler.SpoonResource;
9 import spoon.compiler.builder.JDTBuilder;
10 import spoon.processing.Processor;
11 import spoon.reflect.declaration.CtElement;
12 import spoon.reflect.declaration.CtType;
13 import spoon.reflect.factory.Factory;
14 import spoon.reflect.visitor.Filter;
15 import spoon.support.compiler.jdt.CompilationUnitFilter;
16 import spoon.support.compiler.jdt.FactoryCompilerConfig;
17 import spoon.support.compiler.jdt.FileCompilerConfig;
18 import spoon.support.compiler.jdt.JDTBatchCompiler;
19
20 import java.io.File;
21 import java.util.Collection;
22 import java.util.List;
23 import java.util.Set;
24
25 /**
26 * Responsible for building a spoon model from Java source code.
27 *
28 * <p>
29 * The Spoon model (see {@link Factory} is built from input sources given as
30 * files. Use {@link #build()} to create the Spoon model.
31 * Once the model is built and stored in the factory, it
32 * can be processed by using a {@link #instantiateAndProcess(List)}.
33 * </p>
34 *
35 * <p>
36 * Create an instance of the default implementation of the Spoon compiler by
37 * using {@link spoon.Launcher#createCompiler()}. For example:
38 * </p>
39 */
40 public interface SpoonModelBuilder {
41
42 /**
43 * Builds the program's model with this compiler's factory and stores the
44 * result into this factory. Note that this method should only be used once
45 * on a given factory.
46 *
47 * @return true if the Java was successfully compiled with the core Java
48 * compiler, false if some errors were encountered while compiling
49 * @throws spoon.SpoonException
50 * when a building problem occurs
51 * @see #getSourceClasspath()
52 * @see #getTemplateClasspath()
53 */
54 boolean build();
55
56 /**
57 * Builds the program's model with this compiler's factory and stores the
58 * result into this factory. Note that this method should only be used once
59 * on a given factory.
60 *
61 * @param builder
62 * Parameters given at JDT compiler.
63 * @return true if the Java was successfully compiled with the core Java
64 * compiler, false if some errors were encountered while compiling
65 * @throws spoon.SpoonException
66 * when a building problem occurs
67 * @see #getSourceClasspath()
68 * @see #getTemplateClasspath()
69 */
70 boolean build(JDTBuilder builder);
71
72 /** The types of compilable elements
73 * FILES - compiles the java files from the file system, which were registered by {@link #addInputSource(File)} and {@link #addTemplateSource(File)}
74 * CTTYPES - compiles virtual java files, which are dynamically generated from the all top level classes of the CtModel by {@link spoon.reflect.visitor.DefaultJavaPrettyPrinter}
75 */
76 interface InputType {
77 InputType FILES = FileCompilerConfig.INSTANCE;
78 InputType CTTYPES = FactoryCompilerConfig.INSTANCE;
79 /**
80 * responsible for setting the parameters of JDTBatchCompiler, must call setCompilationUnits()
81 */
82 void initializeCompiler(JDTBatchCompiler compiler);
83 }
84
85
86 /**
87 * Generates the bytecode associated to the classes stored in this
88 * compiler's factory. The bytecode is generated in the directory given by
89 * {@link #getBinaryOutputDirectory()}.
90 *
91 * The array of types must be of size 0 or 1. If it's empty,
92 * the types of the factory are compiled.
93 * If it's InputType.FILES, the files given as input are compiled.
94 *
95 *Note that the varargs ... enables this version to be backward compatible for callers.
96 *
97 * @see #getSourceClasspath()
98 */
99 boolean compile(InputType... types);
100
101 /**
102 * Takes a list of fully qualified name processors and instantiates them to process
103 * the Java model.
104 */
105 void instantiateAndProcess(List<String> processors);
106
107 /**
108 * Processes the Java model with the given processors.
109 */
110 void process(Collection<Processor<? extends CtElement>> processors);
111
112 /**
113 * Generates the source code associated to the classes stored in this
114 * compiler's factory. The source code is generated in the directory given
115 * by {@link #getSourceOutputDirectory()}.
116 *
117 * @param outputType
118 * the output method
119 */
120 void generateProcessedSourceFiles(OutputType outputType);
121
122 /**
123 * Generates the source code associated to the classes stored in this
124 * compiler's factory. The source code is generated in the directory given
125 * by {@link #getSourceOutputDirectory()}.
126 *
127 * @param outputType
128 * the output method
129 * @param typeFilter
130 * Filter on CtType to know which type Spoon must print.
131 */
132 void generateProcessedSourceFiles(OutputType outputType, Filter<CtType<?>> typeFilter);
133
134 /**
135 * Adds a file/directory to be built. By default, the files could be Java
136 * source files or Jar files. Directories are processed recursively.
137 *
138 * @param source
139 * file or directory to add
140 */
141 void addInputSource(File source);
142
143 /**
144 * Adds a file/directory (as a {@link SpoonResource}) to be built. By default, the
145 * files could be Java source files or Jar files. Directories are processed
146 * recursively.
147 *
148 * @param source
149 * file or directory to add
150 */
151 void addInputSource(SpoonResource source);
152
153 /**
154 * Adds a list of files/directories (as a {@link SpoonResource} to be built.
155 * By default, the files could be Java source files of Java files. Directories
156 * are processed recursively.
157 *
158 * @param resources
159 * files or directories to add.
160 */
161 void addInputSources(List<SpoonResource> resources);
162
163 /**
164 * Gets all the files/directories given as input sources to this builder
165 * (see {@link #addInputSource(File)}).
166 */
167 Set<File> getInputSources();
168
169 /**
170 * Adds a file/directory to be used to build templates. By default, the
171 * files should be Java source files or Jar files containing the sources.
172 * Directories are processed recursively. Templates are set apart from the
173 * program to be processed for logical reasons. However, if a template was
174 * needed to be processed, it could be added as an input source.
175 *
176 * @param source
177 * file or directory to add
178 */
179 void addTemplateSource(File source);
180
181 /**
182 * Adds a file/directory (as a {@link SpoonResource}) to be used to build templates. By
183 * default, the files should be Java source files or Jar files containing
184 * the sources. Directories are processed recursively. Templates are set
185 * apart from the program to be processed for logical reasons. However, if a
186 * template was needed to be processed, it could be added as an input
187 * source.
188 *
189 * @param source
190 * file or directory to add
191 */
192 void addTemplateSource(SpoonResource source);
193
194 /**
195 * Adds a list of files/directories (as a CtResource) to be used to build templates. By
196 * default, the files should be Java source files or Jar files containing
197 * the sources. Directories are processed recursively. Templates are set
198 * apart from the program to be processed for logical reasons. However, if a
199 * template was needed to be processed, it could be added as an input
200 * source.
201 *
202 * @param resources
203 * files or directories to add.
204 */
205 void addTemplateSources(List<SpoonResource> resources);
206
207 /**
208 * Gets all the files/directories given as template sources to this builder
209 * (see {@link #addTemplateSource(File)}).
210 */
211 Set<File> getTemplateSources();
212
213 /**
214 * Gets the output directory of this compiler.
215 */
216 File getSourceOutputDirectory();
217
218 /**
219 * Sets the output directory for binary generated.
220 *
221 * @param binaryOutputDirectory
222 * {@link File} for binary output directory.
223 */
224 void setBinaryOutputDirectory(File binaryOutputDirectory);
225
226 /**
227 * Gets the binary output directory of the compiler.
228 */
229 File getBinaryOutputDirectory();
230
231 /**
232 * Gets the classpath that is used to build/compile the input sources.
233 */
234 String[] getSourceClasspath();
235
236 /**
237 * Sets the classpath that is used to build/compile the input sources.
238 *
239 * Each element of the array is either a jar file or a folder containing bytecode files.
240 */
241 void setSourceClasspath(String... classpath);
242
243 /**
244 * Gets the classpath that is used to build the template sources.
245 *
246 * See {@link #setSourceClasspath} for the meaning of the returned string.
247 */
248 String[] getTemplateClasspath();
249
250 /**
251 * Sets the classpath that is used to build the template sources.
252 */
253 void setTemplateClasspath(String... classpath);
254
255 /**
256 * Returns the working factory
257 */
258 Factory getFactory();
259
260 /**
261 * Adds {@code filter}.
262 *
263 * @param filter
264 * The {@link CompilationUnitFilter} to add.
265 */
266 void addCompilationUnitFilter(CompilationUnitFilter filter);
267
268 /**
269 * Removes {@code filter}. Does nothing, if {@code filter} has not been
270 * added beforehand.
271 *
272 * @param filter
273 * The {@link CompilationUnitFilter} to remove.
274 */
275 void removeCompilationUnitFilter(CompilationUnitFilter filter);
276
277 /**
278 * Returns a copy of the internal list of {@link CompilationUnitFilter}s.
279 *
280 * @return
281 * A copy of the internal list of {@link CompilationUnitFilter}s.
282 */
283 List<CompilationUnitFilter> getCompilationUnitFilter();
284 }